hyperspell-mcp

Instructions

Implementation Reference

• src/hyperspell_mcp/server.py:99-104 (handler)

  Handler function for the 'List Collections' tool. Registers the tool/resource and implements the logic to fetch and return the list of collections using the Hyperspell API.
  @mcp.tool_or_resource("collection://", name="List Collections") def list_collections() -> list[Collection]: """Get a list of all collections on Hyperspell""" r = mcp.api.collections.list() return Collection.from_pydantic(r.items)
• src/hyperspell_mcp/types.py:32-35 (schema)

  Dataclass schema for Collection objects returned by the tool.
  class Collection(BaseModel): name: str documents_count: int = 0
• src/hyperspell_mcp/server.py:99-99 (registration)

  Decorator that registers the 'List Collections' tool or resource based on server configuration.
  @mcp.tool_or_resource("collection://", name="List Collections")
• src/hyperspell_mcp/types.py:7-29 (helper)

  BaseModel class providing from_pydantic method used to convert API responses to dataclasses in the handler.
  @dataclass class BaseModel: @overload @classmethod def from_pydantic(cls, model: PydanticBaseModel) -> Self: ... @overload @classmethod def from_pydantic(cls, model: Sequence[PydanticBaseModel]) -> list[Self]: ... @classmethod def from_pydantic( cls, model: PydanticBaseModel | Sequence[PydanticBaseModel] ) -> Self | list[Self]: """Convert a Pydantic model to a data class, selecting only the keys that are part of the data class.""" if isinstance(model, Sequence): return [cls.from_pydantic(m) for m in model] data = model.model_dump() # Only select the keys in data that are part of this data class data = {key: value for key, value in data.items() if key in cls.__annotations__} return cls(**data)
• src/hyperspell_mcp/server.py:71-85 (helper)

  Decorator factory method that conditionally registers functions as MCP tools or resources.
  def tool_or_resource(self, uri: str, name: str | None = None): def decorator(fn: Callable): description = fn.__doc__ if self.config.use_resources: self.resource( uri, name=name, description=description, mime_type="application/json", )(fn) if self.config.use_tools: self.add_tool(fn, name=name, description=description) return fn return decorator